跳到主要内容

DocType 变更后字段不显示问题总结与解决方案

问题现象

  • 在本地开发环境中,DocType 新增或修改字段(如 mark 字段)后,前端 desk 可以正常显示。
  • 将代码(json 文件)推送到 Github 并在新环境部署后,虽然 json 文件中有新字段,但 desk 前端却无法看到。
  • 即使执行了 bench migrate,问题依旧。

原因分析

  1. Frappe 的 DocType 定义有两份:

    • 数据库中的 DocType 配置(tabDocTypetabDocField 等表)
    • apps 目录下的 json 文件(如 rg_production_orders.json
  2. frappe 以数据库为准:

    • 你在开发环境用 UI 改 DocType,frappe 会同步到数据库,并导出 json 文件。
    • 你直接改 json 文件,数据库不会自动同步,frappe 只会用数据库里的定义。
  3. bench migrate 不会自动用 json 覆盖数据库 DocType 配置:

    • 这样做是为了防止误删线上字段或数据。
    • 所以 migrate 只做数据库 schema 迁移和 patch,不 reload DocType。

解决方案

1. 手动同步 DocType

每次部署后,必须执行 reload-doc,用 json 文件内容覆盖数据库 DocType 配置:

bench --site [site_name] reload-doc [app_name] doctype [DocType名称]

如:

bench --site site1.local reload-doc rongguan_erp doctype rg_production_orders

2. 批量 reload

如果有多个 DocType,可以批量 reload:

for dt in $(ls apps/erpnextcn/erpnextcn/erpnextcn/doctype/); do
bench --site site1.local reload-doc erpnextcn doctype $dt || true
done

for dt in $(ls apps/rongguan_erp/rongguan_erp/rongguan_erp/doctype/); do
bench --site site1.local reload-doc rongguan_erp doctype $dt || true
done

3. 自动化建议

在自动化部署脚本中,建议在所有 app 安装完毕后、关闭开发者模式前,统一 reload-doc。

示例插入位置:

bench --site ${siteName} install-app erpnextcn
bench --site ${siteName} install-app rongguan_erp

# reload erpnextcn 所有 DocType
for dt in $(ls /home/${userName}/${installDir}/apps/erpnextcn/erpnextcn/erpnextcn/doctype/); do
bench --site ${siteName} reload-doc erpnextcn doctype $dt || true
done

# reload rongguan_erp 所有 DocType
for dt in $(ls /home/${userName}/${installDir}/apps/rongguan_erp/rongguan_erp/rongguan_erp/doctype/); do
bench --site ${siteName} reload-doc rongguan_erp doctype $dt || true
done

bench --site ${siteName} set-config developer_mode 0

最佳实践

  • 开发时:用 UI 改 DocType,改完后导出 json(bench export-fixturesbench export-doc)。
  • 生产/部署时:只用 json 文件做版本管理,部署后自动 reload-doc。
  • 不要直接手动改 json 文件然后指望 migrate 自动同步。

总结

  • frappe 的 DocType 以数据库为准,json 只是导入导出用。
  • 只要你直接改 json,就要 reload-doc。
  • 建议开发用 UI 改,生产用 reload-doc 自动同步。